home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 38 / Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso / -in_the_mag- / reader_requests / dice_v3.15 / doc / fdtoinline.doc < prev    next >
Text File  |  1999-01-26  |  6KB  |  152 lines
  1.  
  2. dcc/fdtoinline                              dcc/fdtoinline
  3.  
  4.                    FDTOINLINE.DOC
  5.  
  6.  
  7. SYNOPSIS
  8.     FDTOINLINE fdfile hdrfile [-o inline_header_file]
  9.  
  10.     For FDTOINLINE to operate properly two files are required -- the .FD
  11.     file for the library and a prototype file for the library.    The exact
  12.     path specification of the prototype file is also important as it is
  13.     used verbatim by the generated inline header file.
  14.  
  15.     fdfile        specifies the .FD file we wish to generate inline
  16.             calls for
  17.  
  18.     hdrfile        specifies the prototype file describing the
  19.             library functions via standard ANSI C prototypes.
  20.  
  21.     -o inline_hdr    specifies the output file that FDTOINLINE is
  22.             to create.
  23.  
  24. DESCRIPTION
  25.     FDTOINLINE will generate an inline header file based on two input
  26.     files. The two input files required are the .FD file for the library in
  27.     question and a header file containing standard ANSI C prototypes for
  28.     the library.
  29.  
  30.     FDTOINLINE will generate a special #include file which #include's the
  31.     originally specified prototype file and then appends appropriate junk
  32.     to cause the calls to be made in an inline fashion when the -mi option
  33.     to DCC is used.
  34.  
  35.     Since FDTOINLINE attempts to #include the original prototype file and
  36.     since you normally name the output file the same as the original
  37.     prototype file with the exception of placing it in a different directly,
  38.     you must be sure that your specification of the original prototype
  39.     file be complete enough so that when you #include the generated header
  40.     file said file will be able to #include the original prototype file
  41.     without accidently #including itself.
  42.  
  43.     Why do we name FDTOINLINE's generated header file the same as the
  44.     original prototype file and stick it in a different directory?  The
  45.     answer is simple -- it allows us to turn on and off inline library
  46.     calls with a DCC switch (-mi) without requiring us to modify our source
  47.     code.  A random source file would include the commodore standard
  48.     prototypes in the following manner:
  49.  
  50.     #include <clib/exec_protos.h>
  51.  
  52.     Since DICE scans DINCLUDE: before it scans DINCLUDE:AMIGA20, our
  53.     generated prototype files (DINCLUDE:CLIB/*_PROTOS.H) will overide the
  54.     commodore standard prototype files (DINCLUDE:AMIGA20/CLIB/*_PROTOS.H).
  55.     However, our generated prototype files must be able to include the
  56.     commodore standard prototype files as part of their operation, so a
  57.     more explicit path specification for the original prototype is required
  58.     when one runs FDTOINLINE to generate an inline capable file.  The
  59.     command we use to generate our inline files can be illustrated by the
  60.     following example:
  61.  
  62.     1> cd dinclude:
  63.     1> fdtoinline amiga20/fd/exec_lib.fd amiga20/clib/exec_protos.h -o clib/exec_protos.h
  64.  
  65.     Note carefully the specification of the original prototype file... it
  66.     is sufficiently explicit enough so that it will not be confused with
  67.     the generated inline file allowing the inline file to access the
  68.     original file.
  69.  
  70. GENERATING PROTOTYPE FILES FOR CUSTOM LIBRARIES
  71.  
  72.     In order to prevent mixing of DICE distribution includes and your own
  73.     custom includes, prototype files, and whatnot, we provide the
  74.     DINCLUDE:PD directory which DICE automatically scans.  Any custom
  75.     includes or generated inline prototype files or whatnot should be
  76.     included in this directory.  We suggest that you put all of your
  77.     non-standard includes and custom library prototypes / inline header
  78.     files under this directory.
  79.  
  80.     The proscribed method for generating custom inline header files
  81.     is as follows:
  82.  
  83.     (1) MakeDir DINCLUDE:pd/protos if it does not already exist
  84.  
  85.     (2) MakeDir DINCLUDE:pd/fd     if it does not already exist
  86.  
  87.     (3) MakeDir DINCLUDE:pd/clib   if it does not already exist
  88.  
  89.     (4) Place the prototype file provided along with the library in
  90.     DINCLUDE:PD/PROTOS.  For example, DINCLUDE:PD/PROTOS/FUBAR_PROTOS.H
  91.  
  92.     (5) Place the .FD file provided along with the library in
  93.     DINCLUDE:PD/FD.
  94.  
  95.     (6) CD DINCLUDE:PD
  96.  
  97.     (7) FDTOINLINE fd/fubar_lib.fd protos/fubar_protos.h -o clib/fubar_protos.h
  98.  
  99.  
  100.     Your source code would then reference your custom library by including:
  101.  
  102.     #include <clib/fubar_protos.h>
  103.  
  104.     Note that from a coding standpoint your source will conform to the
  105.     Commodore standard for prototype files, even though the actual header
  106.     files are in DINCLUDE:PD/CLIB and DINCLUDE:PD/PROTOS.
  107.  
  108. PROBLEMS WITH CUSTOM PROTOTYPE FILES
  109.  
  110.     A number of problems will come up when you attempt to install custom
  111.     libraries to be compilable under DICE.  I've outlined the major
  112.     problems below.
  113.  
  114.     (1) No .FD file came with the library.  Unfortunately there is not much
  115.     that can be done if you do not have the .FD file.  The .FD file is
  116.     the Commodore standard for all shared libraries and any library
  117.     distributed to the general public should also include an associated
  118.     .FD file.  Your only recourse here is to ask the author of the
  119.     library to provide the appropriate file!
  120.  
  121.     (2) No prototype file came with the library.  Again, this is something
  122.     that the author should have provided but all is not lost if it
  123.     doesn't exist.  You simply have to create a prototype of your and
  124.     assign your best guess for argument types in each library call.
  125.     For example, if a library call returns a string and takes three
  126.     integer arguments you could construct a prototype as follows:
  127.  
  128.     char *NameOfCall(long, long, long);
  129.  
  130.     (3) The prototype file that came with the library requires other
  131.     #include's to be brought in before it.  There will be many cases
  132.     where an author will assume that <exec/types.h> and other
  133.     standard includes have already been #include'd by a source file
  134.     before the author's own prototype file is included.  This is
  135.     incorrect thinking on the authors part and makes use of his
  136.     prototype file difficult.
  137.  
  138.     The workaround is to MODIFY the author's prototype file to make it
  139.     self contained.  For example, if the author's prototype file
  140.     required <exec/types.h> then you would prepend the following to
  141.     his prototype file:
  142.  
  143.     #ifndef EXEC_TYPES_H
  144.     #include <exec/types.h>
  145.     #endif
  146.  
  147.     The conditional #ifndef/#endif is not necessary but will improve
  148.     compilation speed by not including header files that have already
  149.     been included.
  150.  
  151.  
  152.